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Intellectual Property Rights 



IPRs essential or potentially essential to the present document may have been declared to ETSI. The information 
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found 
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in 
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web 
server ( http://webapp.etsi.org/IPR/home.asp ). 

Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee 
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web 
server) which are, or may be, or may become, essential to the present document. 



Foreword 

This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP). 

The contents of the present document are subject to continuing work within TC SCP and may change following formal 
TC SCP approval. If TC SCP modifies the contents of the present document, it will then be republished by ETSI with 
an identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

early working draft; 

1 presented to TC SCP for information; 

2 presented to TC SCP for approval; 

3 or greater indicates TC SCP approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 
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Scope 



The present document defines an API that allows a UICC based SCWS defined by OMA to forward Http requests to an 
Applet and to receive the response from the Applet. It also defines an API for the Applet to register and unregister to the 

sews. 



References 



References are either specific (identified by date of publication and/or edition number or version number) or 
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the 
reference document (including any amendments) applies. 

• In the case of a reference to a TC SCP document, a non specific reference implicitly refers to the latest version 
of that document in the same Release as the present document. 

Referenced documents which are not found to be publicly available in the expected location might be found at 
http://docbox.etsi.org/Reference . 

NOTE: While any hyperlinks included in this clause were vahd at the time of publication ETSI cannot guarantee 
their long term validity. 



2.1 



Normative references 



The following referenced documents are necessary for the application of the present document. 
[1] "Hypertext Transfer Protocol - HTTP/1.1". 

NOTE: available at http://www.ietf org/rfc/rfc26 16.txt . 



[2] 

[3] 

[4] 
[5] 

[6] 

[7] 



[8] 
[9] 



ETSI TS 102 241: "Smart cards; UICC Application Programming Interface (UICC API) for Java 
Card(TM)™". 

OMA "Smartcard -Web Server Enabler Architecture", OMA-AD-Smartcard-Web-Server-Vl-0- 
20070209-C. 

OMA "Smartcard- Web-Server", OMA-TS-Smartcard-Web-Server-Vl-O-20070209-C. 

Sun Microsystems Java Card'^'^ Specification: "Java Card'^ 2.2.2 Application Programming 
Interface". 

Sun Microsystems Java Card^^ Specification: "Java Card"""^ 2.2.2 Runtime Environment (JCRE) 
Specification". 

Sun Microsystems Java Card^^ Specification: "Java Card^^ 2.2.2 Virtual Machine Specification". 



NOTE: SUN Java Card Specifications can be downloaded at http://iava.sun.com/products/iavacai'd 



ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application 
providers". 

ETSI TS 102 225: "Smart Cards; Secured packet structure for UICC based applications". 



2.2 



Informative references 



The following referenced documents are not necessary for the application of the present document but they assist the 
user with regard to a particular subject area. 

Not applicable. 
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Abbreviations 



For the purposes of the present document, the following abbreviations apply: 

AID Application IDentifier 

API Application Program Interface 

CAT Card Application Toolkit 

CAT_TP Card Application Toolkit Transport Protocol 

FFS For Further Study 

Http HyperText Transfer Protocol 

HTTP HyperText Transfer Protocol 

JCRE Java Card'^ Run-time Environment 

sews Smart Card based Web Server 

NOTE: According to OMA specifications [3] and [4]. 



Description 



4.1 



Architecture 



The present document describes an API and a SCWS Runtime Environment that enables Java Card^^ platform based 
applets, defined in [5], [6], [7], to register to and unregister from an SCWS implemented in the UICC, defined by OMA 
in [3] and [4]. 

The API enables a registered Applet to receive an incoming Http request that is forwarded by the SCWS. The API 
provides the necessary methods to allow registered Applets to respond with a correctly formatted Http response to the 
SCWS. The API provides means to the Applet to access the Http header data and the content of the Http request, to 
send specific Http status values, and to set the content of the Http response. 

The Http request and response are defined in the Hypertext Transfer Protocol - HTTP/1.1 [1]. 

This API allows application programmers to extend the functionality of the SCWS defined by OMA in [3] and [4]. 



£75/ 



Release 8 



ETSI TS 102 588 V8.2.0 (2011-01) 



sews 



Java Card 
Packages 



j: 



102 221 based 
Applications 
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Applet or 
USIM Applet) 

ADF File 
System Server 



uicc. access 
package 



Other 

Applications 
not based on 
102 221 



j: 



Toolkit Applet 

(e.g. Toolkit 

service, 

Remote 

Management 

Applications, 

Browser 

Applications) 



uicc. toolkit 
package 



UICC. system 
package 



Java Card Runtime Environment 



CAT Runtime 
Environment 



UICC. sews 
package 



sews Runtime 
Environment 



Items that are defined in this specification 

Figure 1 

Smartcard Webserver (SCWS): handles Http request as defined by OMA in [3] and [4] and provides a mechanism to 
the Applet for the registration. 

sews Runtime Environment: Extensions to the Java Card^^^ platform described in [5], [6], [7] and the CAT Runtime 
Environment described in TS 102 241 [2] to facilitate the communications between Applets and the SCWS. 

Applet: these derive from javacard.framework.Applet and provide the entry points: process, select, deselect, install as 
defined in the "Java Card^*^ 2.2.2 Runtime Environment Specification" [6]. 

Registry of the SCWS: is provided as a JCRE entry point object defined in [6], and provides an interface to the Applet 
to pass a name to the SCWS for registration and deregistration. The registry is part of the SCWS Runtime Environment. 

SCWS API: consists of the package uicc. sews, provides the methods to register and deregister, to receive Http requests 
and to provide the content of the Http response. 



4.2 Registration and deregistration 



The registration of Applets to the SCWS enables the server to invoke a specific applet when it has received an Http 
request. Applet Instances can register with a name to the SCWS. 

The mapping of the Http request to the name of the applet is described by OMA in [3] and [4] by the use of 
administrative commands { [FFS] other non-Http based mechanism. } . It is not possible to register several Applets under 
the same name to the SCWS. It is possible for an Applet to register several times with different names to the SCWS. 

The Applet can also deregister from the SCWS. When the Applet deregisters from the SCWS the mapping information 
is deleted from the registry. 

If an Applet is deleted then the registration information in the SCWS Registry is deleted by the SCWS Runtime 
Environment. 

If the Applet is in a non selectable state, its registration to the SCWS is still valid. 
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4.3 Invocation 

The sews invokes the Applets according to the mapping information when the complete Http request has been 
received by the SCWS. 

Only an Applet that is in selectable state can be invoked by the SCWS. 

If Applet execution ends without any invocation of the flush() method and without throwing an exception the SCWS 
shall finalize the response and send it. 

4.4 Transfer of response data 

There are two transfer modes defined for the SCWS API: "fixed buffer size mode" and "chunked mode". 

The API offers a method to switch between transfer modes. This method must be called before calling finalizeHeader() 
and before the first call of appendContent(). 

The default transfer mode is "fixed buffer size". 

The header attributes ("Content-Length: xxx" and "Transfer-Encoding: chunked") will be set according to the active 
transfer mode by the SCWS runtime environment. The Application is not supposed to set these attributes. 

The SCWS runtime environment is not required to enforce this policy. The behaviour of the SCWS runtime 
environment is undefined if the application manipulates the header attributes for content length and transfer encoding. 

In "fixed buffer size mode" an exception will be thrown by appendContent() if the buffer size would be exceeded. 

In "fixed buffer size mode" no data are sent out before the application has called ih&flush() method, subsequent calls 
are permitted but have no effect. 

In "chunked mode" a call of flush() sends all data in the response buffer. If there are no data in the response buffer no 
data will be sent. 

If a call of appendContentO exceeds the buffer size in "chunked mode" the data in the response buffer will be sent 
implicitly. 

Exceptions thrown by the invoked Applet shall not be propagated to the terminal, and the SCWS shall send an error 
status code according to HTTP 1.1 [1]. In case of "chunked mode", some response data could have already been sent by 
the SCWS. In this case, no error shall be sent by the SCWS. In case of "fixed buffer size mode", the status code is 
always sent by the SCWS. 

4.5 Response header management 

Response header fields can be provided by applications by using the appendHeaderVariable() methods. 
The following headers shall be added by the SCWS if not provided by the application: 
• Status line, indicating success status (200 - OK or 204 - No Content). 

Server field, containing "OMA Smart Card Web Server" or a customized string. 

If status code 200 is returned. Content-type field, indicating "text/plain". 

If status code 200 is returned. Content-length and Transfer-Encoding, according to clause 4.4. 



• 



• 



• 
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4.6 ProactiveHandler and ProactiveResponseHandler 

The rules about the availabiUty of the ProactiveHandler and the ProactiveResponseHandler as defined in 
TS 102 241 [2] are extended according to the following rules: 

The ProactiveHandler shall be available for applets that are invoked by an incoming Http request (i.e. by one of the 
methods doGet(), doPost(), doDelete(), doHead(), doOptions(), doPut(), and doTrace(J) in the same way as if it would 
be available for an applet which was triggered by the method processToolkit() in the current card state. If available, the 
ProactiveHandler shall be available for these applets until the termination of the method that was invoked by the 
incoming Http request. 

The availability of the ProactiveResponseHandler shall depend on the availability of the ProactiveHandler as defined 
in TS 102 241 [2], except that it is available until the termination of the method that was invoked by the incoming Http 
request. 

Applets implementing the Toolkitlnterface as defined in TS 102 241 [2] in addition to the SCWS interface will be 
triggered in the processToolkit() method upon reception of any Toolkit event. 

Implementation dependent on a central CAT_TP multiplexing application as defined in TS 102 225 [9] may be present 
in the card. It must not block the ProactiveHandler when an applet is invoked by an incoming Http request. 
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Annex A (normative): 

Application invocation API by a UICC Webserver for the 

Java Card™ platform 

The source files for the (102588_Annex_A_Java.zip and 102588_Annex_A_HTML.zip) are contained in 
ts_102588v080200p0.zip, which accompanies the present document. 
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Annex B (normative): 

Application invocation API by a UICC Webserver for the 

Java Card™ platform 

The export files for the uicc.scws package (102588_Annex_B_Export_Files.zip) are contained in 
ts_102588v080200p0.zip, which accompanies the present document. 

NOTE: See the "Java Card™ 2.2.2 Virtual Machine Specification" [7]. 
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Annex C (normative): 

Application invocation API by a UICC Webserver for the 

Java Card™ platform package version management 

Table C.l describes the relationship between each TS 102 588 specification version and its packages AID and Major, 
Minor versions defined in the export files. 

Table C.I 



TS 102 588 


uicc.scws package 




AID 


Major, Minor 




AO 00 GO GO G9 GO 05 FF FF FF FF 89 14 00 00 00 


1.0 



The package AID coding is defined in TS 101 220 [8]. The uicc.scws package AID is not modified by changes to Major 
or Minor Version. 

The Major Version shall be incremented if a change to the specification introduces byte code incompatibility with the 
previous version. 
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Annex D (informative): 
Change history 
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SCPt071053 


015 
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Fix the "OPTION" method documentation and name 
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018 
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Adding missing exceptions in method signatures 
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SCP#41 


SCP-090125 
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Availability of the ProactiveHandler and the 
ProactiveResponseHandler 
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8.1.0 


SCP#46 


SCP(1 0)0269 


SCPTEC(1 0)0478 


023 




A 


Addition of HTTP status code 


8.2.0 


SCP#46 


SCP(1 0)0266 


SCPTEC(1 0)041 2r1 


021 




F 


Clarification of availibility of ProactiveHandler 


8.2.0 



£75/ 



Release 8 



14 



ETSI TS 102 588 V8.2.0 (2011-01) 



History 



Document history 


V8.0.0 


June 2010 


Publication 


V8.1.0 


October 2010 


Publication 


V8.2.0 


January 2011 


Publication 















£75/ 



